home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 26 / Cream of the Crop 26.iso / program / ddj0897.zip / RCSC.ZIP / PACKAGES / SC22.ZIP / READ.ME < prev    next >
Text File  |  1990-04-18  |  23KB  |  498 lines
  1.            Small C Compiler / Small Assembler
  2.                        User Notes
  3.  
  4.  
  5. COPYRIGHT NOTICES
  6.  
  7. Compiler:  Copyright 1982, 1983, 1985, 1988 J. E. Hendrix
  8. Library:   Copyright 1984 J. E. Hendrix, L. E. Payne
  9. Assembler: Copyright 1988 J. E. Hendrix
  10.  
  11. All rights reserved.
  12.  
  13.  
  14. COMPILER VERSION 
  15.  
  16. This diskette contains version 2.2 (revision level 117) of the Small C 
  17. compiler as implemented under PC/MS-DOS 2.1 (and later versions) by 
  18. James E.  Hendrix.  This version differs from 2.1 primarily in that the 
  19. code generating and optimizing parts of the compiler have been 
  20. extensively rewritten, making them much more lucid and noticably 
  21. improving the quality of the code generated.  The source files have been 
  22. reorganized into a more logical arrangement.  No new features have been 
  23. added.  
  24.  
  25. Compared to the previous release (version 2.1, revision level 75), this 
  26. compiler generates programs with EXE files that are between 4% and 13% 
  27. (typically 10%) smaller and TWICE as fast.  Although much more 
  28. optimizing is done, the compiler itself is about 6% smaller and runs 
  29. slightly faster than the previous version.  About one fourth of its time 
  30. is spent optimizing.  
  31.  
  32. The main reason for the doubling of the speed of programs compiled with 
  33. Small C is a revision to the library function iscons() so that it calls 
  34. DOS only for the first refererence to a file, thereafter it returns a 
  35. value based on its memory of DOS's original answer.  It turned out that 
  36. this was a very very slow DOS call, and since iscons() is called in 
  37. fgets(), fgetc(), and _read(), which form a thread, the penalty was 
  38. high.  So, not surprisingly, avoiding this DOS call on a byte-by-byte 
  39. basis yielded spectacular improvements in read times.  
  40.  
  41. Another reason for the speed improvement is a rewrite of the character 
  42. classification functions -- isalpha(), isdigit(), etc.  Whereas they 
  43. used to test a character's value with "if" statements, they now simply 
  44. reference an array with the questionable character as a subscript and 
  45. return a bit indicating whether or not the character is of the specified 
  46. class.  This sped up these functions by THREE times.  Since these 
  47. functions are now so small, they have been grouped into a single source 
  48. module IS.C.  
  49.  
  50. Finally, there is the general improvement in speed produced by the 
  51. additional code optimizing, which goes far beyond what was being done.  
  52. While not as good as the major C compilers, the code Small C now 
  53. generates is quite respectable.  For example, AR.EXE is 1.13 times the 
  54. size of the same program compiled with Microsoft 4.0.  
  55.  
  56. For those interested in studying the compiler itself, perhaps the nicest 
  57. thing about version 2.2 is the rewrite of the code generation and 
  58. optimizing logic, the reorganization of the source files, and the 
  59. revised p-code names.  These changes have made the compiler much more 
  60. understandable.  First, the p-code names now follow a system so that it 
  61. is possible to tell exactly what a code does without looking at the 
  62. assembly text it generates.  The regrouping of the source code clearly 
  63. differentiates between front end, back end, and parsing functions.  All 
  64. of the p-codes appear alphabetically in the function setcodes() together 
  65. with the assembly strings they generate, making it unnecessary to forage 
  66. around for the exact effect of a p-code.  Finally, the peephole 
  67. optimizer has been generalized to take both the p-code sequence to be 
  68. matched and the optimizing instructions from integer arrays to which it 
  69. is directed.  A single array contains both of these for a given 
  70. optimization case.  One can easily understand the optimizations by 
  71. studying these arrays -- which are initialized with p-code symbols and 
  72. other symbols that form a kind of language.  There is no need to study 
  73. the optimizer itself to read these optimization actions.  
  74.  
  75. This version fixes a number of problems with the earlier version -- most 
  76. notably, a tendency of scanf() to drop characters.  Read the file 
  77. HISTORY for a complete listing of the revisions since 2.1.  
  78.  
  79.  
  80. SMALL ASSEMBLER
  81.  
  82. This diskette contains an executable copy of Small Assembler.  This is 
  83. an assembler written in Small C primarily for use in processing Small C 
  84. output.  Small Assembler runs slowly compared to Microsoft's
  85. assembler, but it is adequate for use with Small C, making it 
  86. unnecessary to purchase an expensive assembler. Small Assembler is 
  87. available as a product in its own right -- complete with source code and 
  88. a user's manual.
  89.  
  90. This assembler is essentially compatible with the Microsoft product.  
  91. Either may be used with the Small C compiler.  Differences are 
  92. primarily: (1) many Microsoft directives are not supported (most notably 
  93. the conditional assembly directives), (2) macros employ positional 
  94. rather than named parameters, (3) not all of the Microsoft expression 
  95. operators are supported, and (4) most of the expression operators in the 
  96. C language are supported.  
  97.  
  98.  
  99. THE DISTRIBUTION DISKETTE
  100.  
  101. The following files are included on this disk: 
  102.  
  103.    READ.ME       This documentation.
  104.    REGISTER      User registration form.
  105.    HISTORY       History of Small C rivisions.
  106.    CCC.BAT       Procedure to compile the compiler.
  107.    CC.EXE        Executable Small C compiler.
  108.    CC.H          Header file for compiling Small C.
  109.    CC1.C         Small C source (part 1).
  110.    CC2.C         Small C source (part 2).
  111.    CC3.C         Small C source (part 3).
  112.    CC4.C         Small C source (part 4).
  113.    NOTICE.H      Copyright header for compiling Small C.
  114.    STDIO.H       Standard header file for all compiles.
  115.    CLIB.LIB      Small C object library for use with LINK.
  116.    CLIB.ARC      Small C library source archive.
  117.    CLIBARC.LST   List supplied to AR for building CLIB.ARC.
  118.    AR.EXE        Executable archive maintainer.
  119.    AR.C          Archive maintainer source.
  120.    ASM.EXE       Executable Small Assembler.
  121.  
  122.  
  123. DOCUMENTATION
  124.  
  125. The Small C compiler is fully described in "A Small C Compiler: 
  126. Language, Usage, Theory, and Design"  by James E. Hendrix.  Copies are 
  127. available from: 
  128.  
  129.                      M&T Publishing, Inc.
  130.                      501 Galveston Dr.
  131.                      Redwood City, CA  94063
  132.                      Phone: 1 (800) 533-4372
  133.  
  134. In this book, you will find a full treatment of the Small-C language, 
  135. the use of the Small-C compiler, and the theory of operation of the 
  136. compiler.  It documents revision level 112 of the compiler.  Any 
  137. additional revisions to the compiler on this diskette are described in 
  138. the file named HISTORY.  
  139.  
  140. Until the assembler is released as a separate product, its only 
  141. documentation is that which is found here in this file.  
  142.  
  143.  
  144. USING THE COMPILER
  145.  
  146. The Small-C compiler takes in a subset of the full C language, and 
  147. generates Microsoft assembly language output.  It supports only integer 
  148. and character data types.  Arrays are limited to one dimension.  It does 
  149. not support arrays of pointers, structures, or unions.  Also lacking are 
  150. sizeof, casts, #if expr, #undef, and #line. External functions are 
  151. automatically declared, but external variables (defined in another 
  152. source file) must be declared explicitly.  Functions always return 
  153. integer values. Globals may be initialized using the = syntax, but 
  154. locals cannot be initialized. Locals are always automatic, and the 
  155. specifiers auto, static, extern, register, and typedef are not accepted 
  156. at the local level. Only extern is accepted at the global level. 
  157. Character variables are expanded with sign-extension when they are 
  158. referenced; character constants are not sign extended, however.  
  159.  
  160. The steps involved in compiling a program are documented in the file 
  161. C.BAT.  
  162.  
  163. Examples of invoking the compiler follow: 
  164.  
  165.   CC                       compile console input
  166.                            giving console output
  167.  
  168.   CC <FILE1 -L1 -P         compile FILE1 giving console
  169.                            output, list the source as
  170.                            comments in the output, and
  171.                            pause on errors
  172.  
  173.   CC <FILE1 >FILE2 -M      compile FILE1 giving FILE2
  174.                            and monitor progress by
  175.                            listing function headers on
  176.                            the console
  177.  
  178.   CC FILE1                 compile FILE1.C giving FILE1.ASM
  179.  
  180.   CC FILE1 FILE2           compile FILE1.C then FILE2.C
  181.                            giving FILE1.ASM
  182.  
  183.   CC FILE1 FILE2 >FILE3    compile FILE1.C then FILE2.C into
  184.                            a single program in FILE3
  185.  
  186.   CC FILE1 >FILE2 -NO -A   compile FILE1.C giving FILE2,
  187.                            negate optimizing, and 
  188.                            sound the alarm on errors
  189.  
  190. Any number of files may be concatenated as input by listing them in the 
  191. command line; in that case stdin is not used. Standard DOS file 
  192. specifications, including logical devices, are accepted. The listing 
  193. switch has two forms: 
  194.  
  195.           -L1   lists on stdout (with output) as comments
  196.           -L2   lists on stderr (always the console)
  197.  
  198. If the compiler aborts with an exit code of 1, there is insufficient 
  199. memory to run it.  Pressing control-S makes the compiler pause until 
  200. another key is pressed, and control-C aborts the run with an exit code 
  201. of 2.  Press ENTER to resume execution after a pause because of a 
  202. compile error. If input is from the keyboard,  control-Z  indicates end-
  203. of-file, control-X rubs out the pending line, and Backspace rubs out the 
  204. previous character.  
  205.  
  206.  
  207. USING THE ASSEMBLER
  208.  
  209. The Small Assembler reads an ASCII source file and writes an object file 
  210. in the standard .OBJ file format.  This makes the Small Assembler 
  211. compatible with LINK which comes with PC/MS-DOS.  In fact, Small 
  212. Assembler has no linker of its own; it must be used with the DOS linker.  
  213.  
  214. The command line for invoking the assembler has the following format:
  215.  
  216.           ASM source [object] [-C] [-L] [-NM] [-P] [-S#]
  217.  
  218. Command-line arguments may be given in any order.  Switches may be 
  219. introduced by a hyphen or a slash.  The brackets indicate optional 
  220. arguments; do not enter the brackets themselves.  
  221.  
  222.  source   Name of the source file to be assembled.  The default, and 
  223.           only acceptable, extension is ASM.  Drive and path may be 
  224.           specified.  
  225.  
  226.  object   Name of the object file to be output.  It must have a OBJ 
  227.           extension to be recognized as the output file.  Drive and path 
  228.           may be specified.  If no object file is specified, output will 
  229.           go to a file bearing the same name and path as the source 
  230.           file, but with a OBJ extension.  
  231.  
  232.  -C       Use case sensitivity.  Without this switch, all symbols are 
  233.           converted to upper-case.  With this switch, they are taken as 
  234.           is; upper- and lower-case variants of the same letter are 
  235.           considered to be different.  With or without this switch, 
  236.           segment, group, and class names are always converted to upper-
  237.           case in the output OBJ file.  
  238.  
  239.               Note: The .CASE directive may be included at the
  240.               beginning of the source file to produce the same
  241.               effect as this switch.
  242.  
  243.  -L       Generate an assembly listing on the standard output file.  If 
  244.           you do not want the listing to go to the screen, then provide 
  245.           a redirection specification (e.g., >prn or >abc.lst) to send 
  246.           it whereever you wish.  
  247.  
  248.  -NM      No macro processing.  This speeds up the assembler somewhat.  
  249.           Macro processing is NOT needed for Small-C output files.  
  250.  
  251.  -P       Pause on errors waiting for an ENTER keystroke.
  252.  
  253.  -S#      Set symbol table size to accept # symbols.  Default is 1000.
  254.  
  255. If an illegal switch is given, the assembler aborts with the message
  256.  
  257.         Usage: ASM source [object] [-C] [-L] [-NM] [-P] [-S#]
  258.  
  259. The null switch (- or /) can be used to force this message.
  260.  
  261. If the assembler aborts with an exit code of 1, there is insufficient 
  262. memory to run it.  Pressing control-S makes the assembler pause until 
  263. another key is pressed, and control-C aborts the run with an exit code 
  264. of 2.  Press ENTER to resume execution after a pause because of an 
  265. error.  
  266.  
  267. Symbols (names of labels, etc.) may be up to 31 characters long.  Every 
  268. character has significance.  Symbols may contain the following 
  269. characters: 
  270.  
  271.         1. alphabetic
  272.         2. numeric
  273.         3. the special characters _, $, ?, and @.
  274.  
  275. Labels must be terminated by a colon.  All other names which begin a 
  276. line must not have a colon.  
  277.  
  278. Comments begin with a semicolon (;) and continue to the end of the line.  
  279.  
  280. ASCII strings are must be delimited by quotes (") or apostrophies (').  
  281. The backslash (\) may be used to escape the delimiter when it appears 
  282. within the string.  
  283.  
  284. Only integer numbers are recognized by the assembler.  Numeric constants 
  285. must begin with a numeric (decimal) digit.  The default base (radix) for 
  286. numeric constants is decimal.  Bases may be specified explicitely by 
  287. attaching a letter to the right end of the number as follows: 
  288.  
  289.              b or B    binary
  290.              o or O    octal
  291.              q or Q    octal
  292.              d or D    decimal
  293.              h or H    hexadecimal 
  294.  
  295. Expressions may produce the Boolean values 1 for "true" or 0 for 
  296. "false".  This differs from Microsoft which yields FFFFh for "true".  
  297.  
  298. Expression evaluation is done with 32-bit precision.  The low order bits 
  299. are then used according to the needs of the instruciton being generated.  
  300. Expressions may contain the following operators: 
  301.  
  302.         (highest precedence)
  303.         -------------------------------------  unary operators
  304.         BYTE  PTR      take following operand as a byte
  305.         WORD  PTR      take following operand as a word (2 bytes)
  306.         DWORD PTR      take following operand as a double word (4 bytes)
  307.         FWORD PTR      take following operand as a far word (6 bytes)
  308.         QWORD PTR      take following operand as a quad word (8 bytes)
  309.         NEAR  PTR      consider the following label near
  310.         FAR   PTR      consider the following label far
  311.         OFFSET         the offset to the follownig operand
  312.         SEG            the segment address of the following operand
  313.         xS:            segment register override (e.g. ES:)
  314.         [  ]           indirect memory reference
  315.         !              Logical not
  316.         -              minus
  317.         ~              one's complement
  318.         NOT            one's complement
  319.         ------------------------------------- 
  320.         *              multiplication
  321.         /              division
  322.         %              modulo
  323.         MOD            modulo
  324.         ------------------------------------- 
  325.         .              addition of indirect reference displacement
  326.         +              addition
  327.         -              subtraction
  328.         ------------------------------------- 
  329.         <<             shift left
  330.         >>             shift right
  331.         ------------------------------------- 
  332.         !=             not equal
  333.         NE             not equal
  334.         <=             less than or equal
  335.         LE             less than or equal
  336.         <              less than
  337.         LT             less than
  338.         >=             greater than or equal
  339.         GE             greater than or equal
  340.         >              greater than
  341.         GT             greater than
  342.         ==             equal
  343.         EQ             equal
  344.         ------------------------------------- 
  345.         &              bitwise AND
  346.         AND            bitwise AND
  347.         ------------------------------------- 
  348.         ^              bitwise exclusive OR
  349.         XOR            bitwise exclusive OR
  350.         ------------------------------------- 
  351.         |              bitwise inclusive OR
  352.         OR             bitwise inclusive OR
  353.         ------------------------------------- 
  354.         (lowest precedence)
  355.  
  356. Notice that these precedence levels agree with the C language and 
  357. disagree with the Microsoft assembler.  This should only rarely be a 
  358. problem, however, since most expressions are very simple.  Nevertheless, 
  359. parentheses may be used to override the default precedences.  
  360.  
  361. The dollar sign ($) represents the value of the location counter at the 
  362. beginning of the current instruction.  
  363.  
  364. This version of the assembler knows only the instruction set of the 8086 
  365. processor.  It does not know the 8087 instructions.  Future editions 
  366. will know all of the 80x86 processors and their coprocessors.  
  367.  
  368. The following directives are recognized by this verson of the assembler.  
  369. Only the parameter values shown are supported, however.  
  370.  
  371.      -------------------------------------------------
  372.             .CASE          (see the -C switch above)
  373.      -------------------------------------------------
  374.      name   EQU constantexpression
  375.      alias  EQU symbol
  376.      -------------------------------------------------
  377.      name   =  constantexpression
  378.      -------------------------------------------------
  379.      name   MACRO
  380.             ...
  381.             ENDM
  382.      -------------------------------------------------
  383.      name   SEGMENT  [align]  [combine]  [class]
  384.                       BYTE     PUBLIC     'name'
  385.                       WORD     STACK
  386.                       PARA     COMMON
  387.                       PAGE
  388.             ...
  389.             ENDS
  390.      -------------------------------------------------
  391.      name   GROUP segmentname,,,
  392.      -------------------------------------------------
  393.      name   PROC [distance]
  394.                   NEAR
  395.                   FAR
  396.             ...
  397.             ENDP
  398.      -------------------------------------------------
  399.             ASSUME NOTHING
  400.             ASSUME register:name,,,
  401.                    CS       segmentname
  402.                    SS       groupname
  403.                    DS       NOTHING
  404.                    ES
  405.                    FS
  406.                    GS
  407.      -------------------------------------------------
  408.             PUBLIC name,,,
  409.      -------------------------------------------------
  410.             EXTRN name:type,,,
  411.                        BYTE
  412.                        WORD
  413.                        DWORD
  414.                        FWORD
  415.                        QWORD
  416.                        NEAR
  417.                        FAR
  418.      -------------------------------------------------
  419.      [name] DB expression,,,
  420.      [name] DW expression,,,
  421.      [name] DD expression,,,
  422.      [name] DF expression,,,
  423.      [name] DQ expression,,,
  424.      -------------------------------------------------
  425.             ORG expression
  426.      -------------------------------------------------
  427.             END [start]
  428.      -------------------------------------------------
  429.      name   MACRO
  430.      -------------------------------------------------
  431.             ENDM
  432.      -------------------------------------------------
  433.  
  434. Macro definitions begin with the MACRO directive and end with the ENDM 
  435. directive as shown above.  Macro definitions cannot be nested; however, 
  436. macro expansions (or calls) can.  Since macro arguments are not named, 
  437. none appear with the MACRO directive.  Within the body of the macro, the 
  438. symbol ?1 indicates places where the first argument of the macro call is to 
  439. go.  Likewise, ?2 designates locations where the second argument goes, 
  440. and so forth through ?0 for the 10th argument.  Macro argument 
  441. substitution is done without regard to context, so you are not limited 
  442. to replacing whole symbols with an argument.  For instance, you might 
  443. write J?0 for the mnemonic of a conditional jump.  The first argument of 
  444. the call might be LE, resulting in a mnemonic of JLE.  
  445.  
  446. To avoid "Redundant Definition" errors when a macro containing labels is 
  447. called more than once, you may write labels within the body of a macro 
  448. as @n, where n is a decimal digit.  This allows ten such labels per 
  449. macro.  The assembler maintains a running count of such labels as 
  450. assembly progresses.  Whenever such a label is found in a macro 
  451. expansion, it is replaced by a label of the form @x, where x is the 
  452. running count.  
  453.  
  454. Small Assembler makes no distinction between warnings and hard errors.  
  455. If it issues any error messages in a run, then it finishes the run with 
  456. an exit code of 10 which can be tested by means of an IF statement in a 
  457. batch file.  In that case, it also deletes the OBJ file so that you 
  458. cannot attempt to link and execute an erroneous program.  The following 
  459. error messages may be issued by the assembler: 
  460.  
  461.    Per Run
  462.  
  463.    - No Source File        no input file is specified or it doesn't exist
  464.    - Error in Object File  an error occurred wirting the OBJ file
  465.    - Missing ENDM          the program ended within a macro definition
  466.    - Missing END           the program ended without an END directive
  467.    - Deleted Object File   the OBJ file was deleted because of errors
  468.  
  469.    Per Segment
  470.  
  471.    - CS Not Assumed for    
  472.      this Segment          there is no ASSUME for CS and this segment
  473.  
  474.    Per Line
  475.  
  476.    - Phase Error           the address of a label differs between passes
  477.    - Bad Expression        an expression is written improperly
  478.    - Invalid Instruction   this mnemonic/operand combination is not defined
  479.    - Redundant Definition  the same symbol is defined more than once
  480.    - Bad Symbol            a symbol is improperly formed
  481.    - Relocation Error      an relocatable address is written as absolute
  482.    - Undefined Symbol      an undefined symbol is referenced
  483.    - Bad Parameter         a macro call does not give a required parameter
  484.    - Range Error           a self-relative reference is too distant
  485.    - Syntax Error          an instruction or directive is improperly formed
  486.    - Not Addressable       "END xxx" has something other than an address
  487.    - Segment Error         a segment is not defined or referenced properly
  488.    - Procedure Error       a procedure is not defined properly
  489.  
  490.  
  491. USING THE ARCHIVE MAINTAINER
  492.  
  493. Comments in the front of AR.C describe the operation of the archive 
  494. maintainer AR.EXE.  To extract all of the modules out of the library 
  495. archive, enter the command: 
  496.  
  497.                           AR -X CLIB.ARC
  498.